home *** CD-ROM | disk | FTP | other *** search
/ HPAVC / HPAVC CD-ROM.iso / ADVHSC18.ZIP / ADVHSC.DOC next >
Text File  |  1994-11-04  |  13KB  |  348 lines
  1. ANTARES DEMO DiViSiON DOCUMENTATION - HSC PLAYER PASCAL VERSION
  2.  
  3. May    13 1994  - Version 1.5 -  Written By Access/ADV [PUBLiC RELEASE]
  4. June   18 1994  - Version 1.6 -  Functions Added 
  5. July    2 1994  - Version 1.7 -  Bugfix / Functions Added
  6. August 28 1994  - Version 1.8 -  CleanUp / Correction Of Documentation 
  7.  
  8.                         A N T A R E S
  9.  
  10.                       H.S.C.  P L A Y E R
  11.               F O R   T U R B O   P A S C A L   7
  12.        
  13.                       FM Music Power !
  14.  
  15.                         Version 1.8
  16.               
  17.                 Coding & Packaging By Access/ADV
  18.              Original Object Player By Chicken/ECR
  19.  
  20. ══════════════════════════════════════════════════════════════════════════════   
  21. 1 )  H.S.C. ??????
  22.  
  23.    H.S.C. Is The Name Of The Format Used By The FM Tracker Of
  24.    Chicken/ECR. This Unit Allow You To Easily Replay These
  25.    Module In Your Production Without The Need Of Using Assembler.
  26.    Even Beginner Should Normaly Able To Use This Piece Of Code (
  27.    If Not, Return To Your Joystick And Play Doom ;)
  28.    The Advantage Of The Music is in his Size : A Module Took Only +- 15Ko
  29.    This is little in comparaison of SoundTracker Module !
  30.  
  31.                                 
  32. ══════════════════════════════════════════════════════════════════════════════   
  33. 2 )  Package
  34.  
  35.    Normaly, The ZIP Contain The Following Files :
  36.    
  37.    ADVHSC.TPU   -  The Main TPU Used By The Player.
  38.  
  39.    EXAMPLE.PAS  -  A Example Of How To Use These TPU In IRQ Mode
  40.    EXAMPLE.EXE  -  The Compiled Version Of The First Example    
  41.    EXAMPLE2.PAS -  A Example Of How To Use These TPU In Polling Mode 
  42.    EXAMPLE2.EXE -  The Compiled Version Of The Second Example 
  43.    EXAMPLE3.PAS -  Another Example To Show You How To Do Raster & Music
  44.    EXAMPLE3.EXE -  The Compiled Version Of The Third Example
  45.    EQUAL.PAS    -  Show The Use Of The GetPlayerState Function
  46.    EQUAL.EXE    -  The Compiled Version Of The Equalizer Demo
  47.  
  48.    ADVHSC.DOC   -  This File.
  49.    MUZIK.HSC    -  A Little HSC File If You Don't Have The HSCTracker 
  50.                    Package.
  51.  
  52.    ANTARES.EXE  -  A Little Information File For Our Group 
  53.                         ( Music By Our TPU )
  54.    
  55.    It's Possible ( And Probable :) That You Will Find Some Other Files Inside
  56.    The Archive ( BBS Addy, Group Addy ). Simply Note That These
  57.    Files Are *NOT* From Us.  
  58.                           
  59.  
  60. ══════════════════════════════════════════════════════════════════════════════   
  61. 3 )  The TPU : ADVHSC.TPU
  62.  
  63. Note : A ## Symbol Indicate Modification Since The Last Version.
  64.  
  65.  
  66.    This TPU Contain All The Functions You Need To Replay Correctly HSC Files.
  67.    
  68. FUNCTION DETECTADLIB(SUGGESTEDPORT:WORD):WORD;
  69.  
  70.    This Function Tell You About The Presence Of A Compatible
  71.    Adlib Card In Your System. The Function Return The Base Port Of 
  72.    The Card Or FFh If A Error As Occured During The AutoDetect Process
  73.    ( No Card For Example :). SUGGESTEDPORT Is Your Suggestion
  74.    About A Possible Port ( Useful If You Have 2 SoundCards ).
  75.    
  76.    If SUGGESTEDPORT=0 Then Auto Detection Is Used.
  77.  
  78.    This Function Is For Your Information Only, The Player Have His Own
  79.    Adlib Detection Routine.
  80.       
  81.  
  82. PROCEDURE TOGGLERASTER;
  83.  
  84.    This Procedure Toggle The Raster Bar At The Top Of The Screen.
  85.    This Raster Show You The Time Used By The Player To Do His
  86.    Work. If You Don't Understand :    Try! :)
  87.  
  88.    The Procedure Works Like A On/Off Switch.
  89.  
  90. FUNCTION LOADSONG(FILENAME:STRING):BOOLEAN;
  91.  
  92. ##  Now, LOADSONG iS A *FUNCTION* !!!!
  93.  
  94.    This Function Allocate Memory And Load A SongFile Into
  95.    Memory. 
  96.    
  97. ##  Now, Some Error Checking iS Done : If The File Don't Exist Or
  98. ##  There iS Not Enough Memory To Load The Module, The Function Return
  99. ##  FALSE. If All Was Done Correctly ( Module Loaded) A TRUE iS
  100. ##  Returned.
  101.    
  102.    FILENAME Is A Valid DOS Filename ( Don't Forget To Include The 
  103.                                             Extension ! )
  104.                                                            
  105. PROCEDURE CLEARMEM;
  106.  
  107.    This Procedure De-Allocate Memory Allocated By LOADSONG. You
  108.    *NEED* To Call This Procedure Before Exiting ! ( Otherwise, Serious
  109.    Crash Can Occur ! )
  110.  
  111. N.B. Only Needed If You Have Used The LOADSONG Procedure.
  112.  
  113. PROCEDURE SETMODE(MODE:BYTE;OLDINT:BYTE);  
  114.  
  115.    This Procedure Setup The Replay Mode Of The Player.
  116.       
  117.    MODE   = 0  :  The Player Will Use IRQ To Play The Music. ( Default )
  118.           = 1  :  The Player Need To Be Called Throught The Polling Procedure        
  119.                   This Approach Is Better Is You Use Raster, Scroll Or Other
  120.                   Things Like That. ( SEE EXAMPLE2.PAS )
  121.  
  122.    OLDINT = 0  :  The Old Int 1Ch Is Called By The Player ( Probably Used By
  123.                   Another Program. This is The Default Setting ).
  124.           = 1  :  Don't Call The Old Interrupt.                  
  125.                          
  126. PROCEDURE PLAYSONG;
  127.  
  128.    This Procedure Play The Song Previously Loaded By LOADSONG.
  129.  
  130. PROCEDURE PLAYSONGMEMORY(SONG:POINTER);
  131.  
  132.    This Procedure Play A Song Located Somewhere In Memory. SONG
  133.    Is A 32 Bit Pointer To This Song. Useful If You Have HardCoded
  134.    The Music In Your Executable With Utility Like BINOBJ Or
  135.    ZIP2OBJ.
  136.    
  137. TIPS :  Using BINOBJ ->
  138.  
  139.      Your MuZik File = MUSIC.HSC
  140.      Use : 
  141.      
  142.      BINOBJ MUSIC.HSC MUSIC.OBJ MUSICDATA
  143.      
  144.      In Your Program : 
  145.      
  146.      {$F+}
  147.      {$L MUSIC.OBJ}
  148.      Procedure MUSICDATA; External; Far;
  149.      {$F-}
  150.      
  151.      To Play Music :
  152.      
  153.      PLAYSONGMEMORY( @MUSICDATA );
  154.      
  155.      Great, No ? =)
  156.  
  157. PROCEDURE POLLMUSIC;
  158.  
  159.    This Procedure Is Used Only If You Have Put The Player Into
  160.    POLL Mode ( See The SETMODE Procedure ). It *MUST* Be Called
  161.    At Least 18 Time Per Second ( More Is Not A Problem ).
  162.    See Examples For More Information...
  163.  
  164. PROCEDURE SETUSERIRQ(LINK:BOOLEAN;ROUTINE:POINTER);
  165.  
  166.    This Procedure Permit To Link The Player Interrupt To A User
  167.    Own Made Routine. That Will Mean That Each Time The IRQ Is
  168.    Called, The User Routine Will Be Called Too.  The User Routine
  169.    Must End With a RETF Instruction. This One iS Great For Making
  170.    Equalizer For Example.
  171.    
  172.    Parameters :
  173.    
  174.    LINK     =  TRUE  :  Call The User Routine
  175.             =  FALSE :  Don't Call Any User Routine
  176.          
  177.    ROUTINE           :  A 32 Bit Pointer To The User Routine
  178.    
  179.    Tips:  To Obtain The Pointer, Use  
  180.    
  181.       SETUSERIRQ(TRUE,@USERIRQ);
  182.       
  183.       Where USERIRQ Is The Name Of Your Procedure To Call During IRQ.
  184.  
  185. PROCEDURE FADESONG;
  186.  
  187.    This Procedure Turn The Volume Down To Produce A Fade Out Of The Music.
  188.    
  189.    WARNING!  The Procedure Didn't Wait The End Of The Process.
  190.    So You Need To Wait A Little Before Stopping The Music. A
  191.    Delay Of 2-3 Seconds Seem To Be Good.
  192.  
  193. Example :    FADESONG;
  194.              DELAY(3000);
  195.              STOPSONG;
  196.  
  197. PROCEDURE STOPSONG;
  198.  
  199.    This Procedure Stop All Playing.  
  200.    
  201.    WARNING! Memory Is *NOT* Released. You Must Do It By Calling CLEARMEM.
  202.  
  203. Tips: You Could Play A Song Again After Stopping... Simply Call
  204.       PLAYSONG Again :)
  205.  
  206. PROCEDURE GETPLAYERSTATE;
  207.     
  208.     This Procedure Give You Some Information About The Playing Of The
  209.     FM Module. All The Information Are Returned Into A Array Called
  210.     PLAYERSTATE . Here is the Definition Of The Array :
  211.     
  212. Type      PlayerStateType = Record
  213.             Note      : Array[1..9] Of Byte; { Note }
  214.             Instr     : Array[1..9] Of Byte; { Instrument Number }
  215.             Equalizer : Array[1..9] Of Byte; { Equalizer Value }
  216.             Peak      : Array[1..9] Of Byte; { No Music : 0, Music : $FF }
  217.             Pattern   : Byte; { Current Pattern }
  218.             Track     : Byte; { Current Track }
  219.             Position  : Byte; { Current Position }
  220.             Playing   : Byte; { Is There Music Currently Playing? 0=No,1=Yes }
  221.           End;
  222.  
  223. Var PlayerState : PlayerStateType;                                
  224.  
  225.     The Variable is Declared INTO The TPU, So You *DON'T* To Do It
  226.     Yourself. For More Information, See The Example File Called 
  227.     EQUAL.PAS.
  228.  
  229. FUNCTION SONGSIZE:LONGINT;
  230.  
  231.          This Function Return The Size In Byte Of The Loaded Song.
  232.  
  233. ══════════════════════════════════════════════════════════════════════════════   
  234.   
  235. ## 4) Technical Note
  236.       
  237.       Please Note That There iS No More A Second TPU ... Thanks To
  238.       Chicken For Debugging HiS HSCOBJ !
  239.  
  240. ══════════════════════════════════════════════════════════════════════════════   
  241. 5 )  Disclaimer
  242.  
  243.    The Author Cannot Be Held Responsible For Any Damage Due To
  244.    The Use Of This Product. You Use It At Your Own Risk.
  245.  
  246.    So, If You Put The Cat Into The Fridge While Programming or There
  247.    is Radioactive MushRoom Waving In Your PC During Playing, It's Not
  248.    My Fault...OKay ?                                          
  249.    
  250.    Don't Forget That I Do Coding For *FUN* Only ! 
  251.    
  252.    *No Commercial Use Without Written Permission Of The Author*
  253.  
  254.    Bla...
  255.    Bla..
  256.    Bla.
  257.  
  258.    And If You Are *NOT* Happy With This Thingy, DO IT YOURSELF !   |^>
  259.  
  260. ══════════════════════════════════════════════════════════════════════════════   
  261. 6 )  Contacting Antares & The Creator Of ADVHSC ...
  262.  
  263.    So You Want To Join The Antares Fan Club ?  Hum... We Have
  264.    Already A Lots Of People And I Begin To Be Difficult To Manage
  265.    All These Fans... :)  Try Anyway ...
  266.  
  267.          Write To :             Or Give A Call To The Antares WHQ :
  268.    
  269.       Access / Antares              ULTiMAT BBS - ANTARES WHQ
  270.      ( Main OrganiZer )                 + 32-2-375.56.51                 
  271.      Rue Du Millénaire 3           Open 24H A Day / 2400->19200
  272.        7080 Frameries                ZyXel - SysOp : Cobra/ADV
  273.           Belgium  
  274.           
  275.       If Ya Want To Chat With Me, Call +32-65-66.70.40 
  276.       Only *FRENCH* & *ENGLISH* Please !
  277.       ( Decent Hour - Ask For Francois )
  278.           
  279.     Our Group iS Always Looking For New Members... So, If You Feel
  280.     That You Will Have Fun With Us, Contact Me !
  281.  
  282.     - GFX ARE WELCOME ! -          
  283.  
  284. ══════════════════════════════════════════════════════════════════════════════   
  285. 9 )  Some Greets Flying To :
  286.    
  287.    The NFF Crew       -  Hi Spinal! Hope You Will Not See This Things Like A 
  288.                          Offense To Your Own TPU. ;)
  289.                          Your VV MiniTro iS Great!
  290.                          
  291.  Imphobia/Cascada       -  When Speed Mean Something... ;)
  292.  HyperNova              -  Raytrace Rules!
  293.  The iMAGiNE Crew       -  You Did It! her her her Kwel! ;)
  294.  Babylon -5-            -  WiRED ... We Did it!
  295.  The Orme               -  We want more !
  296.  Blue Adonis / Traxx    -  Traxx Members are Real animals! ;)
  297.  The UnderTaker/Tragedy -  My Favorite Belgian House Maker! HardCore RuleZ!!!
  298.  The Planet E DiskZine  -  No More Issue ?
  299.  Extented Architecture  -  Hi Markus! Keep In Touch !
  300.  Sub-Normal             -  RTBF Rules! ;)   Waiting For Your Report
  301.  N-Factor               -  Tseng Labs Rules!
  302.  Melting Pots           -  Houba! Houba! ;)
  303.  $PA                    -  3DS For Ever!
  304.  Tragedy                -  Bam! Bam! wow! ;)
  305.  Outlaws                -  Better Than LD Party No ?  :)
  306.  TFL / TDV              -  Da Belgian Scene iS Alive!
  307.  Radical                -  Autodesk Animator Power! <g>
  308.                            Nice Meeting You! Waiting For Your Report
  309.  
  310.         And To All People Who Attended WiRED'94... See ya Next Year And
  311.         Don't Miss The CD-Rom!
  312.  
  313.    And Of Course To All SysOp & CoSysOp Of Antares HQ & DiSTro !   
  314.    
  315.    Sorry For All The Forgotten ... 
  316.        
  317. ══════════════════════════════════════════════════════════════════════════════   
  318. 10 )  REVISION HISTORY
  319.  
  320. Version 1.0ß   -  First Version
  321.                   Added PlaySongMemory,StopSong,FadeSong
  322.                   PERSONAL USE ONLY          
  323.                   
  324. Version 1.0    -  Added LoadSong,ClearMem,SongSize
  325.                   FOR ANTARES MEMBER ONLY
  326.                   
  327. Version 1.5    -  First Public Release
  328. May 1994          Added SetUserIRQ,ToggleRaster,DetectAdlib,SetMode,PollMusic
  329.                   Rewrite Of The Assembly Part Of HSCOBJ.TPU.
  330.                   Some Experiment With GetPlayerState
  331.  
  332. Version 1.6    -  LoadSong ReWritted
  333. June 1994         Some Debugging...
  334.                   GetPlayerState Removed
  335.                   Size Shrinked Down To ...... 2 Ko Of Code !                  
  336.  
  337. Version 1.7    -  LoadSong One More Time ReWritted (*FIXED* This Time)
  338. July 94           GetPlayerState Re-Added ! Now Equalizer Information!
  339.                   No More 2 Tpu !              
  340.                   We Are Now Using The *NEW* HSCOBJ Version 1.5!
  341.                   *EVEN* Smaller !  ( thanks Chicken!! )
  342.                   More Examples...
  343.  
  344. Version 1.8    -  Documentation Corrected
  345. August 94         Code OptimiZation & CleanUp
  346.  
  347. ══════════════════════════════════════════════════════════════════════════════                     
  348.